package suncertify.contractors;

import suncertify.contractors.exceptions.CloseContractorsException;
import suncertify.contractors.exceptions.ContractorFindException;
import suncertify.contractors.exceptions.ContractorUpdateException;
import suncertify.contractors.exceptions.ReadAllContractorsException;
import suncertify.db.DBAccess;
import suncertify.db.Data;

/**
 * This interface provides an object oriented equivalent for the {@link DBAccess} interface, the {@link Contractor}
 * class in this interface stands for the <code>String[] data</code> parameter in the {@link DBAccess} interface.
 * 
 * <p>
 * This interface is intended to be used by the front tier layers (like the user interface) to access the data exposed
 * by the {@link DBAccess} interface. The intention of this interface is to provide a database independent definition of
 * data interaction.
 * 
 * <p>
 * The interface is implemented by the {@link ContractorsAccessImpl} which provides local (without network) data access.
 * The interface is inherited by the <code>RemoteContractorsAccess</code> interface that provides remote data access.
 * 
 * <p>
 * Example how the interface is used to access the database:
 * 
 * <pre>
 * // This is the path to the database file on the local machine.
 * String databasePath = &quot;C:\\Data\\SCJD\\Copy of Real Assignment\\work-db-2x2.db&quot;;
 * 
 * // Declare the interface variable.
 * ContractorsAccess contractorsAccess = null;
 * 
 * try {
 *     // Create the implementor of the interface. The ContractorsAccessImpl class provides local file access, all
 *     // you need to provide is the path.
 *     contractorsAccess = new ContractorsAccessImpl(databasePath);
 * 
 *     // The database file is read and cached in the ContractorsAccessImpl class.
 * } catch (ContractorsInitializationException e1) {
 *     // If you are here then most probably the file path is incorrect, cannot be read/written or the file is
 *     // corrupt.
 *     return;
 * }
 * 
 * // This search criteria searches the database for all contractors that are named &quot;Dogs with Tools'
 * String[] findCriteria = new String[] { &quot;dogs with tools&quot;, null, null, null, null, null };
 * 
 * // This will hold our search result.
 * Contractor[] contractors = null;
 * 
 * try {
 *     // Execute the search using the defined criteria.
 *     contractors = contractorsAccess.findByCriteria(findCriteria);
 * } catch (Exception e) {
 *     // Catch any errors here.
 * } finally {
 *     // close the database file if you finish accessing the data.
 *     contractorsAccess.closeContractors();
 * }
 * 
 * </pre>
 * 
 * </p>
 */
public interface ContractorsAccess {

    /**
     * Definition for a method that returns all (not deleted) contractors from the database.
     * 
     * @return All (not deleted) contractors from the database.
     * 
     * @throws ReadAllContractorsException
     *             Implementors should throw this exception if the implementation fails.
     * @throws Exception
     *             Implementors should throw this exception for any unexpected errors.
     */
    public Contractor[] getAllContractors() throws ReadAllContractorsException, Exception;

    /**
     * Definition for a method that returns an array of contractors based on a search criteria. The search criteria is
     * defined in {@link DBAccess#findByCriteria(String[])}
     * 
     * @param criteria
     *            The search criteria.
     * @return Array of contractors that match the search criteria.
     * @throws ContractorFindException
     *             Implementors should throw this exception if the implementation fails.
     * @throws Exception
     *             Implementors should throw this exception for any other unexpected errors.
     * 
     * @see DBAccess#findByCriteria(String[])
     */
    public Contractor[] findByCriteria(String[] criteria) throws ContractorFindException, Exception;

    /**
     * Definition for a method that saves the given <code>contractor</code> in the database.
     * 
     * @param contractor
     *            The contractor to be saved in the database.
     * 
     * @throws ContractorUpdateException
     *             Implementors should throw this exception if the update fails due to any exceptions defined in the
     *             {@link Data} methods.
     * 
     * @throws Exception
     *             Implementors should throw this exception for any unexpected errors.
     * 
     * @see DBAccess#findByCriteria(String[])
     */
    public void updateContractor(Contractor contractor) throws ContractorUpdateException, Exception;

    /**
     * Definition for a method that closes the connection to the database. The connection to the database can be an
     * opened file for example.
     * 
     * @throws CloseContractorsException
     *             Implementors should throw this exception if the database close fails.
     * @throws Exception
     *             Implementors should throw this exception for any other unexpected errors.
     * 
     */
    public void closeContractors() throws CloseContractorsException, Exception;
}
